home *** CD-ROM | disk | FTP | other *** search
- .TOPIC:
- Input & Output Commands
-
- VBBS 6.12 Documentation -- 10-B-1
-
-
- ╔════════════════════════════════════════════════════════════════╗
- ║ CHAPTER TEN ANNEX B INPUT AND OUTPUT COMMANDS ║
- ╚════════════════════════════════════════════════════════════════╝
-
-
- READING INPUT
- ═════════════
-
- One of the most common uses of a script is to get some
- information from a user and the script language contains many
- commands to help implement this task. All the commands allow
- for a <prompt> string, but this is optional so you do NOT have
- to use it if you do not want to.
-
- GETYN -> GETYN <variable1> <prompt>
- GETNY -> GETNY <variable1> <prompt>
-
- These two commands show the user whatever is stored within
- the <prompt> and ask for a response of Y, N, or <enter>. The
- GETYN command defaults to Y when then user presses <enter> and
- GETNY defaults to N.
- ex: GETYN $yesorno "Do you wish to continue ? "
-
- RS -> RS <variable1> <prompt>
-
- This command prints the optional <prompt> and then accepts
- a line of input. The input can be no more than 81 characters
- in length, and input is terminated by pressing <enter>.
- ex: RS $yourname "What is your name ? "
-
- RX -> RX <variable1> <prompt>
-
- This command works like the RS command but instead of it
- echoing the keys that the user presses it prints X's. This is
- very useful for password systems.
-
- RW -> RW <variable1> <prompt>
-
- This command works like the RS command with the only real
- difference being that this command has a word-wrapping feature.
- If a word passes the 80 character point it is word-wrapped over
- to the next input line. To prevent the extra characters from
- being placed into the next input statement you will need to
- place 'Buffer Clear' after the last RW input line. See section
- 5.x for more info on buffer commands.
-
- RN -> RN <variable1> <prompt>
-
- This command prints the optional prompt and then accepts
- only numerical input. It will not take any keys but the #'s
- and input is terminated by pressing <enter>.
- ex: RN $number "Enter your favorite number : "
-
-
- VBBS 6.12 Documentation -- 10-B-2
-
-
- RC -> RC <variable1> <prompt>
-
- This command prints the optional <prompt> and then waits
- for a single character to be pressed. The character is stored
- in <variable1> but it is not shown on the screen.
- ex: RC $onechar "Pick a key, any key : "
-
- RR -> RR <variable1> <string2> <prompt>
-
- This command operates in the same way as the RC command
- with only one difference. It will only accept characters that
- are listed in the <string2>, all others will be ignored.
- ex: RR $thisone ARI "A>bort, R>etry, I>gnore ? "
-
- RL -> RL <variable1> <string2> <value3> <prompt>
-
- This command operates similarly to the RR command. It will
- accept any character listed in <string2> and also will accept a
- number between 1 and <value3>. This is the most versatile form
- for getting input, and is most commonly used for creating a
- menu within a script.
- ex: RL $thatone ABC 3 "Choose A, B, C, 1, 2, or 3 : "
-
- RF -> RF <variable1> <prompt>
-
- This command is used to get a filename as input. It will
- only accept input in the format 'xxxxxxxx.xxx' with each 'x'
- being a character. It will only allow legal characters for the
- name and it will not accept globals (* and ?.) The complete
- list of acceptable characters contains A thru Z (uppercase is
- forced automatically) and the symbols => ! # $ _ - (the => is
- not in the list, it is used only for emphasis.)
- ex: RF $filename "Name of file to be uploaded : "
-
- RI -> RI <variable1> <prompt>
-
- This command is nearly identical to the RF command. The
- one difference being that this command accepts the * and ?
- globals in the filename.
- ex: RI $filetoget "Name of file to find (* and ? allowed) : "
-
-
- SHOWING LINE OUTPUT
- ═══════════════════
-
- There are two different ways that you can show output one
- line at a time. While they are slightly different, both accept
- the same formatting information for their output.
-
- TR -> TR <token2> <token3> <token4> ... <token7>
- TS -> TS <token2> <token3> <token4> ... <token7>
-
- These commands can print out up to 6 different tokens using
- a single line. After the last token on the line is printed the
-
-
- VBBS 6.12 Documentation -- 10-B-3
-
-
- TR command performs a carriage return/linefeed while the TS
- command does not.
-
- The three formatting statements are listed below.
-
- %s -> %s<number1> <variable2>
-
- Outputs <variable2> in a field of <number1> spaces and then
- left justifies it.
-
- %i -> %i<number1> <variable2>
-
- Outputs <variable2> in a field of <number1> spaces and then
- right justifies it.
-
- %d -> %d<number1>.<number2> <value3>
-
- Outputs <value3> with the format ###.## where <number1> and
- <number2> are the ### and the .## respectively. The left part
- of the output is padded with spaces and the right is padded
- with 0's. This format uses the absolute value of <value3>, so
- the output is always a positive number.
-
- You can use any numbers within the statements as long as
- you follow the specified syntax. If the field selected is too
- small for the variable then the output will be chopped down to
- fit it into the field.
-
- Example: Results:
- $a = "Green"
- $b = 16.2312
- tr $b " : " %d3.3 $b => "16.2312 : 16.231"
- tr %s10 $a ":" %i10 $a => "Green : Green"
- ts $b " : "
- tr $a " : The End" => "16.2312 : Green : The End"
-
- Note: The quotes are not in the actual output, they are only
- supplied to emphasize the blank spaces.
-
-
-
- COLORIZATION
- ════════════
-
- There are three different ways to change color in the
- script language. All are identical in output, but each has a
- unique form of implementation. Note: <color code> is the number
- number (0-9) or letter (capital A-Z) code that corresponds to the
- colors as listed in the COLORS.TXT file. Also, the input commands
- from section 3.1 (RS, RW, RX, etc.) will all change the color to
- to the user's default prompt setting unless the <prompt> has a
- color code within it.
-
-
- VBBS 6.12 Documentation -- 10-B-4
-
-
- ANSIC -> ANSIC <color code>
-
- This command is executed on a line by itself and changes
- the effective color to that of the selected <color code>.
-
- $<color> -> Special
-
- The $color commands are actually individual tokens that
- resemble variable names. As such, they may be included into
- other strings with the '&' command (section 2.3) or used on
- their own in output statements (TR & TS.)
-
- $<color> color code $<color> color code
- -------- ---------- -------- ----------
- $RED 6 $YELLOW 2
- $BLUE 7 $MAGENTA B
- $GREEN 5 $CYAN 1
- $WHITE U $NORM 0
- $BLACK n/a
-
- The command $BLACK makes very dark letters though they may
- be visible, depending on your system configuration. A common
- use for this is to cover over ANSI music symbols.
-
- Hearts -> Special
-
- The most frequently used way to change colors is to use
- what has been coined 'Heart-code ANSI.' The Heart code is the
- ASCII code 3 and can be created in a couple of different ways.
- If your ANSI driver supports the extended ASCII character set
- you can create the 'heart' by pressing the <CTRL> key and the
- <C> key or it can be made by holding down the <ALT> key, then
- press 3 (or 003 or 259) on the number pad and then releasing
- the <ALT> key. You will have to test this for your particular
- system to see which works for you. You can also create the
- codes by using the full-screen editor to colorize although this
- can be a bit of work. Immediately after the 'heart' you place
- the desired <color code> and when the script actually runs,
- VBBS will show the correct color (you will not see the 'heart'
- or the next character after it.)
-
- Example:
- These -----\_______/ANSIC 6
- three | \TR "Hello ! " $handle
- pieces |
- of code |_______/$stuff = $red & "Hello ! " & $handle
- all do | \TR $stuff
- the exact |
- same thing-/-------<TR "<heart>6Hello ! " & $handle
-
-
- VBBS 6.12 Documentation -- 10-B-5
-
-
- OTHER DISPLAY COMMANDS
- ══════════════════════
-
- EF -> EF <pathfile1>
-
- This command displays the contents of the specified file
- in <pathfile1>. It will pause whenever the users screen fills
- and continue when a key is pressed.
-
- DRAWWAITBAR -> DRAWWAITBAR <value1>
-
- This command draws a string of green o's surrounded by red
- []'s. The number of o's is equal to <value1>. The cursor is
- then placed on the first 'o' so you can write over it with
- another character. See Appendix D for an example.
-
- LOC -> LOC <value1> <value2>
-
- This command places the cursor at the location equal to the
- (x, y) coordinates that match (<value2>, <value1>). Legitimate
- values for <value1> are 1-25 and for <value2> are 1-80. This
- only operates for users of ANSI, Enhanced ANSI, and VGIX.
-
- MENU -> MENU <filename1>
-
- This command displays a menu file stored in your text
- directory (as set in VCONFIG.) VBBS first checks to see if
- <filename>.MNU exists, and shows it if true. Otherwise it
- shows <filename>.ANS if the user has ANSI and <filename>.ASC
- otherwise.
-
- The .MNU files are universal text files colorized with
- VBBS' heart-code ANSI colors. If the user has ANSI then the
- file displays w/ the colors, but if the user does not have
- ANSI then it is displayed without the colors. You can still
- use .ANS and .ASC menus if you like, however.
-
- If ! is the first character of a line in a menu then VBBS
- will only show the line if the user's security level is greater
- than or equal to the three-digit number that follows the '!'.
-
- Examples:
- !255 S) SysOp Menu <== Not shown unless the user has SL >= 255.
- !100 F) Forward <== " " " " " " " >= 100.
-
- NEWPAGE <---
- SUSPENDPAGEBREAK <---
- RESUMEPAGEBREAK <---
-
- These three commands alter the user's page-break pointer.
- This pointer determines how many lines of text have been viewed
- and the user's screen length (as set in defaults) determines
- when a pause should be used. NEWPAGE resets the pointer to 0
-
-
- VBBS 6.12 Documentation -- 10-B-6
-
-
- so the output will scroll for a number of lines equal to the
- value set in the user's defaults. SUSPENDPAGEBREAK turns the
- use of the pointer off completely (no pauses at all), while
- RESUMEPAGEBREAK turns the pointer back on.
-
- PAUSE -> PAUSE <prompt>
-
- This displays the optional <prompt> or the default prompt
- as set in VCONFIG. It then waits for a keypress and erases
- the prompt before continuing.
-
-
-